gsAIM 1.1
Copyright 1999, Eric Shepherd
All rights reserved.

This software is SHAREWARE.  If you use the software for more than 14 days, you must pay the shareware fee.  To do so, visit http://orders.kagi.com/?QGC to order online.  A printable order form can be downloaded from my web site.  Until the software is registered, preferences and buddy lists cant be saved.

Please support Apple II software development by paying for this software.

There appear to be some Marinetti problems that can cause connection problems using gsAIM.  In particular, it appears that if it takes multiple tries to connect to your ISP, the system will be unstable and may crash.  I strongly recommend rebooting in between attempts to connect to your ISP if you have trouble getting online.

What Is It?
gsAIM is an NDA for System 6.0.1 that uses Richard Bennetts Marinetti TCP/IP stack to let Apple IIgs users participate in Instant Messaging sessions with users of AOL Instant Messenger.  With gsAIM, you can send and receive instant messages with other gsAIM users, as well as with Mac and PC users that have AIM installed on their computers.

System 6.0.1 is required, as is Marinetti 2.0.

Note: This software was written without the knowledge or permission of America Online, Inc., and any changes AOL makes to their server architecture could cause gsAIM to cease functioning.  If this happens, Ill revise the software as soon as possible.

Installing gsAIM
First, make sure youve installed Marinetti, following the instructions that come with it.

Once thats done, just copy the gsAIM NDA into your System folders Desk.Accs directory, and the IdleTime extension into the System.Setup directory in your System folder, then restart your Apple IIgs.  Youre ready to go!

If youve previously used one of the prerelease versions of gsAIM, be sure to create a *:System:Preferences:gsAIM directory and move the gsAIM.Settings and gsAIM.Buddies files from your System folder into that new directory; gsAIM 1.1 requires that these files be there.

Getting Started
Youll need either an AOL or AOL Instant Messenger (AIM) account.  You can get a free AIM account by visiting http://www.aim.aol.com and filling out a signup form.

Next, you should open the Sound control panel and configure the sounds that gsAIM uses.  This is optional; you dont have to use the sound notification features, but if you like having sounds, feel free to use them.

The sounds you need to configure are: Connected to Service, Disconnected from Service, Task Failed, and Received Message.  Some of these are only available if the Sound control panel has been patched using a utility like the sound patcher that comes with Spectrum 2.x.  I dont provide a utility for this myself at this time.

Note: Currently, the Enabled Feature and Disabled Feature sounds are used for "buddy logged in" and "buddy logged out" respectively.  A future version of gsAIM will be more reasonable about this.

Once you have an account and have the sounds configured, youre ready to set up gsAIM.  Open up the gsAIM NDA by selecting it in the Apple menu.  The product registration window will appear.  If you want to register gsAIM, see the section "Registering gsAIM" below.  Otherwise, wait 10 seconds and click the "Not Yet" button when it becomes available.

This should present you with the gsAIM Sign On window.

The gsAIM Sign On window has two edit boxes, one for your AIM username, and one for your AIM password.  Fill these out.  The Save Password checkbox, if checked, tells gsAIM to save your password so you dont have to type it every time.  Your username is always saved.

When youre ready to connect, click the Sign On button.  If youre not connected to the Internet, a window will appear and show you progress information from Marinetti (if you have that option on in the TCP/IP control panel) while the Internet connection is established.

Then another window will appear, displaying status information as the AIM connection is started up.  If your password or username is invalid, youll be informed.  If the login fails for any reason, an alert will let you know what went wrong, and youll be returned to the Sign On window.

Note:  During the login process, you can use the Apple-. (period) keystroke to cancel logging in.  This may take a few moments to register, and it may continue through a few steps of the login process before it stops, but it will cancel (this isnt 100% reliable due to the server architecture, but it usually works).

Once the connection is established, the Connected to Service sound is played, the Connecting to AIM window goes away, and the buddy list window appears.  You can click the IM button to send an instant message, double-click someone in your buddy list to send them a message, or receive messages.

To the left of the name of a person in the buddy list is an icon that indicates whether theyre logged in via AOL or AIM (youll see either an AOL logo or a little globe), and displays a watch icon if theyre idle.

You can add buddies to your buddy list by choosing the Add option in the popup menu in the buddy list window.  This will display a dialog box asking for the username of the person to add to your buddy list.  You can, likewise, remove a buddy from your list by selecting them then choosing Delete.

If you want to see your entire buddy list, and add and delete buddies from it, choose the Edit option in the buddy list popup menu.  The buddy list editor window will appear, showing all your buddies (whether theyre online or not).  The Add button lets you add a new buddy, and the delete button deletes the currently-selected buddy.

You can get information about a buddy (their profile and other information) by selecting the buddy, then choosing Info from the popup menu.  The dialog that appears can be dismissed by clicking the OK button.  If theyre idle, youll see the time, in hours and minutes, that theyve been idle right below their username.

The About option in this menu tells you about the software, and displays, in the lower-left corner, who the software is registered to.  If its not registered yet, youll see "* NOT REGISTERED *".

Sending Messages
When you click the IM button in the buddy list window, a Send Instant Message window will appear.  Fill out the To field with the username of the person to whom you want to send a message, and the larger edit box with the message to send.  Click Send to transmit the message.  If theyre not online, youll see an alert telling you so.

You can send an IM to a buddy by double-clicking them in the buddy list.  If you want to send to someone not in your buddy list, simply click the IM button and change the To field to the appropriate username.

When the message is sent, the Send Instant Message window will close, and a new Instant Message window will appear.

Instant Messages
The Instant Message window appears whenever you send a new message to someone, or when you receive a message from another person.

This window has two text boxes, a Send button, an Add Buddy button, and an Info button.  The upper text box contains a complete transcript of the conversation, including your messages and the messages received by the person youre talking to in that window (each persons username is displayed in front of the message, in bold type).

The lower text box is used to enter a new message to send to the person youre talking to in that window.  Type in your message and press Return to send it, or click the Send button.

If you want to add the person to your buddy list, click the Add Buddy button and theyll be immediately added to the list.  You can get information about the person youre talking to by clicking the Info button.

If someone sends you an instant message that you find unappropriate, and you want to punish them for it, click the Warn button.  A dialog box will appear asking you to confirm this, and to indicate whether or not you want to remain anonymous when you send the warning.  Every AIM user has a warning level, which ranges from 0% to 100%.  The higher their warning level, the fewer messages theyre allowed to send and receive per minute.  If their warning level reaches 100%, their AIM account is cancelled.

Warning a user raises their warning level; if you do it anonymously, their warning level goes up less.  Over time, a users warning level goes down gradually.  Warning levels can be seen in the Info window for a user, and are displayed in the buddy list in parentheses after the users name.  Keep in mind that you can be warned too (an alert will appear telling you if this happens), so be careful how you treat others.

Also, if someone sends you an unsolicited message, dont respond to it unless youre sure you want toif you respond, they can warn you!  You can only warn someone if theyve sent you a message.

Each Instant Message window has the name of the user youre talking to in the windows title.

You may have up to 20 Send Instant Message and Instant Message windows open at once.  Thats up to 20 instant message conversations you can have ongoing at the same time, right on your Apple IIgs!  To start another conversation, you can either click the IM button in the Buddy List window again (or double-click a buddys name), or reply to a new message you receive from someone else.

Logging Off
When you close the Buddy List window, you should be automatically logged off of AIM.

Being Idle
If five minutes passes without your typing on your keyboard or clicking the mouse, and you have the IdleTime extension installed, gsAIM will tell the AIM server that youre idle.  This causes the icon next to your name in other peoples buddy lists to change to a watch icon.  As soon as you click the mouse or press a key, this returns to normal.

People can continue to send messages to you while youre idle.  If you want an automatic response to be sent when this occurs, create a file called gsAIM.IdleMsg in the *:System:Preferences:gsAIM directory.  This file, which you can create using Teach or any other text editor, may contain up to 500 characters of text, which will be sent automatically to people that send you messages while youre idle.

This text shouldnt contain any special formatting.

The idle response feature will be configurable within gsAIM itself, using a preference dialog box, in gsAIM 1.2.  This feature is provided as a temporary measure until the full implementation is ready.

Registering gsAIM
gsAIM is shareware, and costs US $10.  When you decide to register the software, you have two choices:

1. Pay online.  Visit http://orders.kagi.com/?QGC and fill out the form there.  Secure ordering is available for your protection.  You can pay by credit card or First Virtual banking.  Be sure to enter your gsAIM serial number (found in the "Please Register gsAIM" dialog box) in the Comments field on the order form.  If you forget this, your registration will be delayed.

2. Pay by mail.  You can download an order form from http://www.sheppyware.net/gsAIM.  Print this out, fill out the form, and mail it to the address on the form.  Be sure to include your check, if youre paying by check, and dont forget to write your gsAIM serial number on the form.

Once Kagi receives your payment, they will forward your information to me, and I will issue a registration code and send it to you.  Be sure to include an email address with your registration.  Since gsAIM is an Internet product, I assume you probably have one.

Once you receive the registration code, open gsAIM.  In the registration window, type your name in the first edit field, and the registration code in the second.  Type the registration code exactly the way its provided to you.  Once you do that, click the Register button.  If youve typed in the registration code correctly, your software is registered and all the features are enabled!

Important: Be sure to keep a copy of the registration code.  If you need to install gsAIM on multiple computers, youll have to request a registration code for each computer you want to install it onto.  To do this, email the serial numbers for each additional computer to sheppy@sheppyware.net.  Include your original registration code and your full name; if you dont, Ill have to ignore your request.

Info and Such
Report bugs, or make comments to sheppy@sheppyware.net.  You may also discuss the software in the A2 message board on Delphi, but all bugs reports must be emailed to sheppy@sheppyware.net.  Otherwise I may not see them, and that would suck.

Thanks to all my testersthis one was a huge pain in the neck to test:

Kirk Mitchell		(he who had the most problems getting it
			to work)
Ryan Suenaga		(he who had no Marinetti connection but
			complained anyway)
Tony Ward		(he who had a few problems which hopefully
			are all fixed)
Tony Diaz		(he who had few major problems but found
			lots of silly little things that I did
			stupid)
Joe Kohn			He who is missing the "M" in "gsAIM."

Thanks also to the handful of people that paid the registration fee even before the software was completed.

Special thanks to Richard Bennett for creating Marinetti and for tolerating the occasional annoying question.

Extra-special thanks to my wife, Sarah, who rarely saw me while I was working on this (especially when I was rushing to get the first public alpha version out the door Christmas Eve).

Thanks for using gsAIM!  Please visit http://www.sheppyware.net/software/gsAIM for more information.


March 1, 1999.